Documentation for xcomment.sty1

Timothy Van Zandt2


section1-8pt4pt

*Abstract The LATEX style option verbatim.sty, by Rainer Schöpf, allows one to redefine an environment to be a comment, and thereby selectively omit certain environments when typesetting a document. Suppose instead that one wants to typeset only selected environments? For example, one might want to print only a document's tables and figures, without having to enclose all the text outside these environments within comments. This style option allows such selection.

section1-8pt4pt

Usage notes

This style file defines a new environment, |xcomment|, which permits one to typeset only selected environments, without having to enclose all the text outside these environments within comments. The main interest in such a feature is that it allows document styles to have great control over what parts of a document are typeset, thus extending the modularity of LATEX. For example, this option was originally written for use in a document style for seminar notes and slides. The main text of the input file consists of the notes for a seminar, and each slide goes in a |slide| environment. A simple modification of the style options allows one to typeset only the slides, only the notes, or both together, in a variety of styles.

xcomment The |xcomment| environment has as a single mandatory argument a list (possibly empty) of environments, separated by commas and with no spaces. Within the |xcomment| environment, only text within each of the specified environments is typeset. The || command can also be used directly, with the same argument, and it would typically go in the preamble. Invoking the || command is equivalent to putting |
\begin{xcomment}\vert at the invocation of the command or immediately after \ver... ...{document}\vert, whichever occurs later in the document, and \vert\end{xcomment}
| just before the end of the document.

For example, if |table,figure| is put in the preamble, only tables and figures are typeset (but see || below). If the list of environments is empty, as in |
\begin{xcomment}{}\vert, the \vert xcomment\vert environment is essentially like... ...ment, text is processed a line at a time and discarded until \vert\end{xcomment}
| or ||environment|| is encountered, where environment is to be included. The remaining text on the line is not thrown away, as it is in verbatim.sty. Instead, it is rescanned, and the only restrictions are that it have balanced braces and that it not contain commands that again shift into and out of ``comment'' mode.

This is an important feature, because the included environments may have arguments that are best placed on the same line as the ||environment|| command. However, the rescanning creates a temporary file. By default, the file is |xcomment.tmp|. The command ||file|| causes file to be created instead. || suppresses the creation of a temporary file; the leftover text is simply discarded. || also suppresses the creation of a temporary file, but in this case the text is simply inserted without being rescanned (i.e., with category codes 0 (escape |||), 1 (begin group ||), 2 (end group ||) and 6 (parameter |#|) switched to 12 (other).

The command || is executed between the environments that are typeset. Its default definition is |

|.

The command 

    \newxcomment[|\meta{environment list}|]{|\meta{name}|}
defines || and the |name| environment to work like || and the |xcomment| environment. A list of environments to be included can be given as an optional first argument to ||, in which case the new command and environment do not take an argument. For example, if you put |[]mycomment| in the preamble, the |mycomment| environment works like the |comment| environment in verbatim.sty, except for the rescanning.

The command ||environment list|| is provided to disable the floating of environments in the list (also separated by commas and without spaces), since if there are only floats and no text, the floats will accumulate to the end of the document and TEX may run out of memory.